package rolesystem.core;

/**
 * This interface allows to act within the rolesystem,
 * being registered and thus identified.
 * An instance implementing this interface can be obtained
 * through the method reqRegistration of the interface RoleSystem.
 * @see RoleSystem#reqRegistration
 */
public interface RoleRegistration
{
	/**
	 * Listens to an event occurred to this registration.
	 * This method returns as soon as an event occurs.
	 * @return The occurred event.
	 */
	public RoleEvent listen() throws RoleException;


	/**
	 * Listens to an event occurred to this registration.
	 * This method returns as soon as an event occurs or the specified
	 * timeout expires.
	 * @param timeout The maximum time to wait, in milliseconds; if it is
	 * 0, this method behaves like the one without timeout.
	 * @return The occurred event, or null if no event is available.
	 */
	public RoleEvent listen(long timeout) throws RoleException;


	/**
	 * Listens to an event occurred to this registration.
	 * This method returns immediately.
	 * @return The occurred event, or null if no event is available.
	 */
	public RoleEvent listenNoWait() throws RoleException;


	/**
	 * Does an action through this registration.
	 * @param action Action to do.
	 */
	public void doAction(RoleAction action) throws RoleException;


	/**
	 * Returns the identifier assigned to this registration.
	 * @return The identifier assigned to this registration.
	 */
	public int whoAmI() throws RoleException;


	/**
	 * Dismisses this registration.
	 */
	public void dismiss() throws RoleException;
}
